                  NerdTracker 2 FINAL BETA v2.1 Win32 Version
                      official documentation v8.16.2005

                Use MS-DOS edit or a 100% compatible program
               to view this file if you want it to look right

-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-
                                 
                           Nerdtracker 2 Credits:
     Programming, NES replay code, and .NED file format by Mr. Bananmos
                      ANSI graphic design by Phlum-Dumb
                         Ported to Win32 by thefox

-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-

                     http://nesdev.parodius.com/nt2/

              NT2 is discontinued.  This is the final version.
                         Better late than never.


Index:
        0.      Introduction
        1.      Effects
        2.      Keys
          2.a     Pattern Editor
          2.b     Sample Editor
          2.c     Order Editor
        3.      Instrument Settings
        4.      Advice and Suggestions
          4.a     Using the Keyboard for Music
          4.b     Using the DPCM Channel
          4.c     Using the Noise Channel
          4.d     Bugs!
          4.e     Optimizing
          4.f     Tricks
        5.      Replay Program
          5.a     Introduction
          5.b     Usage
        6.      Troubleshooting
        7.      Credits


-==========================================================================-


0.  System Requirements:


        - Soundblaster (or 100% Compatible) Soundcard
        - x86 233 Mhz
        - DOS


-==========================================================================-


1.  Effect:         What it does:

        1xx     Portamento up.  Slides pitch up.
        2xx     Portamento down.  Slides pitch down.
        3xx     Portamento to note.  Slides pitch to note.
        4xy     Vibrato, x = speed, y = depth.  Sine pitch modulation.
        7xy     Tremelo, x = speed, y = depth.  Sine volume modulation.
        8xy     Arpeggio.  Alternates note between specified half-note values.
        Axy     Volume Slide, value is the speed.  x = up, y = down
        Cxx     Set volume, maximum is $3F.  (NES only has 16 volume
        Dxx     Go to next pattern.                         (levels, though)
        Fxx     Set tempo.  Default is 6.  Lower values are faster.  BPM = 125
        xxx     Theoretically, you could modify the replay program and create
                your own effect, though it would do nothing inside the tracker
                itself.


-==========================================================================-


2.  Keys:
  
  (written with american keyboard in mind, may be different on other systems)


  2.a  Pattern Editor:

        Music keys      See section 4a.
        Space           Inserts a note-off at cursor location.
                         (bug: it works in the PCM channel on the NES replay
                          code, but not in NT2's sound emulation)

        Left Ctrl+L     Load .ned (Type in full filename)
        Left Ctrl+S     Save .ned (Don't press backspace while typing the
                                   filename, or it won't be saved!)
        Right Shift     Starts/Stops playing the song.
        ' and \ or      Select current instrument.
        F9 and F10
        
        F1 through F8   Set octave. (use F8 for the lowest, but the NES
                                     can't go lower than A-0 !)
        Numeric * or ~  Switch between pattern, instrument, and order editors.
        Left Shift+F3   Go to sample editor.
                        (or Left Shift+* which works in DOS)

        Cursor keys     Moves cursor. (hmm..)
        Insert          Inserts blank line at cursor location.  Moves all
                        notes below cursor down.
        Backspace       Delete note above cursor, moves position and
                        everything below it up.
        Delete          Delete note or effect at cursor postion.
        Page Up/Down    Moves cursor up/down by 16 steps.
        Home/End        Moves cursor to the top/bottom of the pattern.
        Enter           Creates DAT and IHD files for use with NES replay code.
        Escape          Escape!  Exits the program.


  2.b  Sample Editor:

        L       load sample (Format is 1bit Delta-PCM.  An 8to1bit converter
                is available at http://nesdev.parodius.com/)
        Numeric *  switch between sample editor, notetable, and instruments.

  
  2.c  Order Editor:

        left/right cursor  Select track.
        up/down cursor  Select order position
        + and -         Set pattern in selected position.
        space           Set current position as loop-back point.
        insert          Insert new pattern in selected position.
        delete          Delete pattern in selected position.
                         (bugs: change track patterns to 0 before deleting,
                          also be sure your last order position doesn't use
                          all pattern 0's, or that entry is removed upon
                          save/load)


-==========================================================================-


3.  Instrument Settings:


        Duty cycle      Shape of squarewave, 4 possible settings
        Hold note       Hold note.  Required, unless Timelength is set
        Envelope fix    Set to ON if you want volume control (you should)
        Inst. Volume    Default volume of instrument
      / Frequency Var.  \
     |  Freq. ChngSpeed  | These settings are no longer supported, so don't
     |  Hi to Lo         | mess with them.
      \ Freq. Range     /  
        Timelength      Use this if 'hold note' is turned off
      / Arpeggio X      \
     |  Arpeggio Y       | Auto-arpeggio settings
      \ Arpeggio Z      /
        Vibrato Speed   Auto-vibrato speed
        Vibrato Depth   Auto-vibrato depth
        Tremelo Speed   Auto-tremelo speed
        Tremelo Depth   Auto-tremelo depth
        Volume fade     Auto-volume fade
        Volume fade=UP  Volume will fade up
        Looped noise    Use to make metallic sounds with noise channel
        Auto portamento Automatically slides frequency down
        Portamento=UP   Auto-portamento will go up
        Unlabeled 1     Reverse arpeggio (lower instead of higher)
        Unlabeled 2     Non-looped auto-arpeggio


-==========================================================================-


4.  Advice and Suggestions:
    
  
  4.a  Using the Keyboard for Music:

        Are you not familiar with other tracking programs?  Then, it really
        helps to know what keys correspond to notes on a musical keyboard.
        "Q" is C, "2" is C#, "W" is D, "3" is D#, "E" is - guess what - E.
        The same pattern repeats until the "P" key, which is high E.
        There's a bottom row too, starting at "Z" (being C) and going until
        "M" (being B).  If you know that that there is no E# or B# (as you
        should anyways), the pattern is really easy to follow.  I highlighted
        the sharp keys with a green magic marker on my keyboard, for visual
        reference.  (Note: If you do this, don't put ink on the top of the
        keys unless you like your fingers changing colors!  Heheh.)

  
  4.b  Using the DPCM Channel:

        NT2 uses instruments, similar to .XI instruments in how several
        samples can be loaded into one instrument.  You'll need to have 5
        samples (with each one 1 half-tone higher than the one before it) 
        of the same sound if you want to have a usuable frequency range
        from one sample.

        There is no instrument file saving, so the best way to save your
        instruments is to save them in a blank .NED.

        The NES's frequency control is only *4* bits (yeesh).  If sample #1
        is a C note, then you should set sample #1's frequency value for C-2 
        (or any other octave) to $C in the sample editor.  Now things 
        start to get wierd.  Set E-2 to $D, G-2 to $E, and C-3 to $F (all
        of them using sample #1).  This is where the half-tone higher samples
        come in, and if you understood what I was just talking about then
        you can probably see the pattern that you'll need to follow.  This
        technique should work fine, as long as sample #1 plays a C note when
        the frequency value is $C.  It's not known if Nintendo designed
        certain values to be notes, or if it's just blind luck that they are.

        Here are some diagrams to explain NT2's PCM instrument interface.
        

  
  PCM Instrument Editor:
                                  Sample Number
                                  
                                      Sample Filenames 
                                       (this is where you hit 'L' to
                 ³ĳ·     load a sample)
                 ߳߳߳
                    Inst Name  0sample1.dmc   
Instrument #01            1sample2.dmc   
(each one can    02            2drum.dmc      
 contain 8       03            3blahblah.dmc  
 samples)        04            4              
                 05            5              
                 06            6              
                 07            7              
                                              
                 ܳܳ
                 

             
  
  PCM Note-table Editor:             

             OctaveĿ
                              00 01 02 03
                             Ŀ
             NoteC 00000000
                           C#00000000
                           D 00000000
                           D#00000000
                           E 00000000
                           F 00000000
                           F#00000000
                           G 00000000
                           G#00000000
                           A 00000000
                           A#00000000
                           B 00000000
                             
                              
             Sample Numberٳ
          Sample Playback Speed



  Sample Playback Speeds:

                0       C-8
                1       D-8
                2       E-8
                3       F-8
                4       G-8
                5       A-8
                6       B-8
                7       C-9
                8       D-9
                9       F-9
                A       G-9
                B       A-9
                C       C-10
                D       E-10
                E       G-10
                F       C-10

        
        Remember that any instrument settings you set for normal instruments
        will have no effect on the PCM channel.  Effects such as volume and
        pitch slides, etc. can't be done with the NES's DMA method of using
        samples.  They are stored in ROM, and are played as-is.  The
        maximum amount of sample data you can use without bankswitching is
        16378 bytes.  It wouldn't be too hard to write the code to do
        bankswitching to get more, but would depend on how the samples were
        arranged.  Contact me if you're wanting to try something like this.

        Also, due to the filtering on the NES's sound the PCM channel is
        significantly quieter and cleaner sounding than most emulators to
        date.  On a real NES, if the pulse channels are too loud, they can
        easily drown out the PCM samples.  Personally, when I use samples I
        keep my pulse channel volumes below 8 because of this.


  4.c  Using the Noise Channel:

        The noise channel has a 4bit frequency range, and that means it can
        produce only 16 unique tones.  The tracker interface doesn't have
        an obvious way of letting you know what notes are what, but if
        you keep the following points in mind, you shouldn't have very much
        trouble using the noise channel.  First, remember that the lowest
        noise frequency is the note E-1, and the highest frequency is G-2.
        Secondly, the tracker will play some noise when you put a note in;
        that sound is not the actual pitch.  This problem is only on the
        noise channel.  Play the song to hear how it actually should sound.

        Noise emulation isn't very accurate in emulation.  Especially the
        'looped' (metallic) noise.  At this time, the emulator that seems
        closest in that aspect is the Nosefart plugin for Winamp.


  4.d  Bugs!:

        The NES's hardware has a bug, or a design feature, or whatever you
        would call it involving writing the high-byte of the frequency.  What
        happens, is that if a vibrato or a portamento affects the highest 3
        bits of the frequency, the sound will snap, crackle, and pop.  So
        basically what you do to work around this is not use vibratos on some
        notes, and remember that it will kinda pop if you do portamentos on
        some notes.  One game where this is noticable is Crash 'n the Boys by
        Technos.  If you have the cartridge, listen to the .NSF first, then
        play the game on NES and hear the difference.  Also, the title screen
        music of Demon Sword uses this feature to a rather nice effect!

        Damian Yerrick looked into the matter, and sent me this:
        
         A-3 A-2 A-1 F-1 D-1 B-0 <-- Those are approximately the
         notes where the NES switches the high byte.

	Chibi-Tech pointed out the following bugs and SNAFUs:

        Changing the duty cycle of instrument $0E will cause a crash when you play
	the song.  Leave it at $00, or save your song often.		

	Setting the xx value of "Set speed" command (Fxx) to 00 will put the NT2
	playback in a permanent lock. It's a legit value for the NT2 replay code,
	indeed (as its main use is to set the frame countdown to infinity -- in
	other words, halting further playback), and is often used to end a song
	without looping. But unfortunately in the program, there's no way to set
	playback to a normal speed again after its set to 00.
	If you accidentally set off command F00 & halt playback (especially prone
	to this mistake if you're trying to input speed-swings while composing your
	track), my best bet is to just correct/omit the command, save your work,
	quit & restart NT2 (to reset the speed tick counter back to default 06),
	load up the track again, and resume work as usual.

	Inputting ANY command in the DPCM track will do nothing, in both the
	tracker & the replay code. Sorry, even "set speed" command Fxx in the DPCM
	track will be ignored, too.  (Note: An exception is the note-off command.
	It works in the replay code but not in the tracker.)

        
  4.e  Optimizing:
               
        NT2's file format works in a very optimization-friendly way.
        Say you want to repeat the same note several times.  E.g.:
        
        E-2 1 A02
              A00       ; volume slide will keep going down at speed 2
        E-2 1 A00
              A00

        You could instead, do this:

        E-2 1 A02
              A00
            1 A00
              A00

        It would sound the same (*), and make the file smaller.  You can
        also change the instrument number to do things like change the
        duty-cycle of a squarewave without affecting the frequency, which
        is great for being able to do duty-cycle or other instrument changes
        during note-slides and such.

        (*): Resetting the instrument in that way will not re-trigger a
             non-looped arpeggio.  It also will not work if you have the
             Hold-Note setting disabled.

        You can also save some space by removing the intrument numbers from
        the pattern in the triangle channel.  Just make sure the first note
        in the pattern has an instrument set.  Since that will not reset the 
        volume, it won't work on the noise or square channels if you are
        using volume effects.


  4.f  Tricks:

        There are lots of different ways people have gone about trying to
        get the most out of chip music, and a good way to learn is to 
        download some NSF and/or SID files, and listen to each channel 
        seperatly.  For instance, you'll notice in some NES music, the 
        triangle and noise channels work together seamlessly to provide 
        the music with a good drumbeat and bassline.  For example, you could
        make a triangle channel instrument that uses the auto-portamento
        effect at a high-rate, put a note in and give it a space or 2
        depending on the tempo then put a note off or your bassline in the
        triangle channel.
        
        Using the non-looped arpeggio effect, with the first arpeggio value 
        at $C will provide a short percussive sound at the beginning of a
        note.

        Using the noise channel along with drum samples will greatly alter
        the sound of the drum, with a snare sample for example you could
        give it a longer decay and/or a brighter quality.  Try using apeggios
        (looped and non-looped) on the noise channel.

        Most importantly, try to develop your own style and techniques.
        That is what makes music worth listening to.  But that will happen
        without you really noticing it, anyways.  :)


-==========================================================================-


5.  Replay Program:


  5a.  Introduction:

        This is what makes Nerdtracker 2 really great; it gives one the
        capability to hear your music on a real NES system.  If you want
        to make an NES game or demo, this is a good way to get music in
        your program quickly if you're not planning on writing your own
        music program.  The only downside is the lack of simultaneous
        music and sound effect playback, though that could be possible
        with some kind of code modifications.

        The playback code, like NT2 itself, was designed and written by
        Bananmos.

  6.   Usage:

        The source code compiles with the x816 assembler by minus.  The
        .NED files are not used directly by the replay program.  Instead,
        NT2 creates these 2 files when you press enter while your song is
        loaded:

        temp.dat        -       pattern, order, and instrument data
        temp.ihd        -       DPCM samples and DPCM note-table

        You'll then run the temp.ihd file through the makedtt.exe program.
        For example:

        makedtt temp.ihd temp.dtt temp.dmc 0

        Would take the temp.ihd file and create temp.dtt (DPCM note-table),
        temp.dmc (DPCM sample data) and set up the sample location to start
        at ROM adress $C000. The NES normally can only play samples located
        higher than $C000.  (But it actually wraps-around to $8000.  See
        Brad Taylor's delta moldulation doc for a complete description of
        it's various features and functions.)

        The latest version of the replay code includes a convenient built-in
        NSF header so you can throw it directly into your favorite NES sound
        emulator.

        If you want to play more than one song with the program, you probably
        have the songs.asm file that I created for Solar Wars' soundtrack.
        Simply edit the .incbin commands to include your own .DAT files.  If
        they use samples, they must all have the PCM instruments and note-
        tables set up in the same way in each song, because they will all
        be using the same note-table.

        If you're putting it into a ROM, put it in at the NSF's load adress
        if it's without the header, or (load address-$80) if the NSF header
        is present.  Then to initialize a song, load the accumulator with
        the song number to play, and the X register with 0 if you want NTSC
        speed or 1 if you want PAL speed, then do a JSR to the init address
        in the NSF header.  Then you JSR to the play address every frame
        (60hz NTSC or 50hz PAL) to play the music.  If you want to stop the
        music with silence, stop running the play code and clear the sound
        registers (you could probably get away with only clearing $4015).


-==========================================================================-


6.  Troubleshooting:


        Q: I'm getting an error that says "BLASTER enviroment not found,
           what the?!...".

        A: NT2 requires your soundcard to have DOS drivers.  You can usually
           find out if you have DOS drivers by typing "set" at the command
           prompt.  There should be a line that says "BLASTER=(your config)".
           Your soundcard maker should have DOS drivers on their website.

        A: NT2 might not work on an operating system that doesn't allow a
           program to communicate directly with the hardware.  Full DOS
	   compatability is required.


        Q: NT2 is running, but I'm not hearing any sound.

        A: Did you give your instrument a volume level, and enable
           'hold note' or 'note length'?

        A: Many DOS programs run into trouble when the soundcard's IRQ is set
           to a high number.  Try the Soundblaster 'default' settings of
           Address=220 IRQ=5 DMA=1, or IRQ=7.  If your soundcard is a
           "Plug-n-Pray", you can change these settings fairly easily in
           windows system properties, but beware of conflicts.


        Q: I still can't get it to work!

        A: Post your problem/question on the NES Music messageboard at
           http://nesdev.parodius.com/

           

-==========================================================================-


7.  Credits:


      Bananmos        bananmos_uv@nonspam.at.hotmail.dot.com.kthx

        creator of NT2, show your appreciation of his work by sending him
        your NEDs!  But remember that NT2 is discontinued.


      Phlumb-Dumb
	did stuff


      thefox          xofeht@gmail.com

        modified NT2 to work in win32.  Send an email for any improvement
        requests.


      Memblers        memblers@nonspam.at.parodius.dot.com.kthx

        wrote most of this document.  If you want your NES music published
        on the web, send it to me in either NED or NSF format.  Don't forget
        to include the song info! (Title, Author, year/copyright)


      Chibi-Tech      sprite@nonspam.at.starplace.dot.com.kthx

        designed the NT2 website, helped with this document.


      Damian Yerrick, skankpit, and others (I forget!)

        helped with this document, and misc. stuff.

        

       Nerdtracker 2 is giftware!  If you get good use out of it, please
       send something to Bananmos to show your appreciation.  =)
                  
                

       Visit http://nesdev.parodius.com/ for more NESdev stuff.
       Post your questions and comments on the 'NES Music' messageboard on
       the website above.

       Thanks to everyone who made writing this document worthwhile.
                                       - Memblers

-==========================================================================-
 
                                  -=EOF=-
